---
title: "React Hooks & Components"
description: "Build custom UIs with our React hooks and components"
icon: "react"
---

## What's This About?

Want to build your own custom chat UI? We provide React hooks and components that make it easy to:
- Create custom chat interfaces
- Manage chat state
- Handle messages and responses
- Build your own UI components

## Basic Setup

First, wrap your app with our `WidgetRoot` provider:

```tsx
import { WidgetRoot } from "@openchatai/widget";

function App() {
  return (
    <WidgetRoot 
      options={{
        token: 'your-token',
        initialMessage: 'Welcome!',
        // More options below...
      }}
    >
      <YourCustomChat />
    </WidgetRoot>
  );
}
```

### Available Options

```typescript
type WidgetOptions = {
  // Required
  token: string,                    // Your authentication token
  
  // Optional
  initialMessage?: string[],        // First messages to show
  apiUrl?: string,                  // Custom API URL
  socketUrl?: string,               // Custom WebSocket URL
  defaultOpen?: boolean,            // Open chat by default
  debug?: boolean,                  // Enable debug mode
  
  // Customization
  organizationName?: string,        // Your company name
  headers?: Record<string, string>, // Custom headers
  
  // Callbacks
  onClose?: () => void,            // Called when chat closes
  onHandoff?: (data: HandoffData) => void, // Called on human handoff
  
  // User info
  user?: {
    name?: string,
    email?: string,
    phone?: string,
    avatarUrl?: string,
    customData?: Record<string, string>,
  },
  
  // Bot customization
  bot?: {
    name?: string,
    avatarUrl?: string,
  },
  
  // Custom components
  components?: {
    key: string,
    component: React.ElementType
  }[]
}
```

## Useful Hooks

### 1. useChat Hook

The main hook for chat functionality:

```tsx
import { useChat } from "@openchatai/widget";

function CustomChat() {
  const { 
    sendMessage,      // Send a message
    state,           // Current chat state
    clearSession,    // Clear chat history
    recreateSession, // Start new session
  } = useChat();

  return (
    <div>
      {state.messages.map((msg) => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      <button onClick={() => sendMessage("Hello!")}>
        Send Message
      </button>
    </div>
  );
}
```

### 2. useConfigData Hook

Access your widget configuration:

```tsx
import { useConfigData } from "@openchatai/widget";

function ChatHeader() {
  const config = useConfigData();
  
  return (
    <header>
      Welcome to {config.organizationName}!
    </header>
  );
}
```

### 3. Message Rating Hooks

Add thumbs up/down to messages:

```tsx
import { useUpvote, useDownvote } from "@openchatai/widget";

function MessageRating({ messageId }) {
  const [upvoteState, upvote] = useUpvote(messageId);
  const [downvoteState, downvote] = useDownvote(messageId);
  
  return (
    <div>
      <button onClick={upvote}>👍</button>
      <button onClick={downvote}>👎</button>
    </div>
  );
}
```

## Custom Message Components

You can create custom components for different message types:

```tsx
import { BotMessage, ComponentProps } from "@openchatai/widget";

// Custom component for weather data
function WeatherDisplay({ data }: ComponentProps<WeatherData>) {
  return (
    <div>
      <h3>Current Weather</h3>
      <p>{data.temperature}°C</p>
    </div>
  );
}

// Use in your chat
function ChatMessages() {
  const { state } = useChat();
  
  return (
    <div>
      {state.messages.map((message, i) => (
        message.type === "FROM_BOT" ? (
          <BotMessage 
            message={message} 
            index={i} 
            key={i} 
          />
        ) : (
          <UserMessage message={message} key={i} />
        )
      ))}
    </div>
  );
}
```

<Note>
Remember to:
- Always wrap your app with `WidgetRoot`
- Handle loading and error states
- Consider mobile responsiveness
</Note>

Need help? Check out our [example repo](https://github.com/openchatai/opencopilot/tree/main/examples) or join our [Slack community](https://slack.opencopilot.so)!